Aminet 12

home *** CD-ROM | disk | FTP | other *** search

/ Aminet 12 / Aminet 12 (1996)(GTI - Schatztruhe)[!][Jun 1996].iso / Aminet / dev / lang / HeliOS4.lha / helios_demo_disk4 / docs / userinterface / StandAlonePrograms.doc < prev next >

Wrap

Text File | 1996-02-26 | 18.1 KB | 454 lines

********************************************* Producing StandAlone Applications with HeliOS ********************************************* Before reading the text below you might like to read "Compilation.doc" for a general introduction to the processes of compiling and executing HeliOS programs. The main HeliOS intepreter is not only used to run HeliOS programs: it can also save out HeliOS programs in various formats. To do this it uses a configurable Interpreter menu function called PRESAVE. The HeliOS system is unlike other programming languages in that its executable output does not always necessarily consist of a single file, but can also employ a system using a standalone "executive module" in conjunction with program "overlay" files. The main HeliOS Interpreter program has menu options to configure the PRESAVE output compilation process into three distinct modes: 1 -> Compile dictionary 2 -> Compile overlay 3 -> Compile standalone These options cause the PRESAVE function to save different kinds of program files as follows: Compile dictionary - This causes TWO files to be generated and saved by the PRESAVE function. These files are a main program overlay file and a vocabulary overlay file for use when the program is to be PRELOADED back into the main Interpreter. In this process the vital information which makes up a HeliOS program is split into two parts, one containing the program code itself, and the other containing "vocabulary" information required for the Interpreter to be able to associate keyboard input with functions defined within the program. When using the standalone compiler "HeliOS_cmp" the main program file is given a ".cmp" suffix, and the vocabulary file a ".cmpv" suffix, but in the case where you are compiling from the main interpreter the "cmp" part is omitted. This allows you to specify the exact filename you prefer for the main program file, and the interpreter/compiler simply add a "V" suffix to the vocabulary file. Both of the compiled files should be kept together, and both will be automatically loaded when you use the PRELOAD function on the main program file. Note that when using the PRELOAD function you only need select the main compiled program file, because the vocabulary file will be automatically loaded at the same time by the HeliOS system. Compile overlay - This causes a single file to be generated for use with the "HeliOS_exe" standalone executive program: this file simply contains the program code in a concisely packed form. The standalone executive does not make any use of vocabulary information, so it only requires the program code overlay. A file (called, for example, MyProgram) generated in this way from the Interpreter can be run using the HeliOS_exe "executive" in the following manner: HeliOS_exe MyProgram This allows the one "executive" program containing all the HeliOS support code to be used to run any number of HeliOS program files, each of which is very small and contains only the specific code relating to the program itself. Compile standalone - This causes a single executable file to be generated, which can be run directly on its own. This option reveals perhaps the main "negative trade off" which the design of the HeliOS system has forced upon us. The problem is that all HeliOS executables must contain ALL the HeliOS support code, and thus are quite large at around 250k each. In fact ALL HeliOS executables are exactly the same size, and consist of the HeliOS "executive" program with the program code already embedded within it. This large size is only a real problem if you want to include several HeliOS programs together on a disk. In this case it would be much better to use the second option mentioned above: to have one HeliOS "executive" and several small overlay program files. The simple single executable HeliOS program can only be generated from the main Interpreter, and its use is quite self-explanatory. HeliOS overlay files can be generated also by using a standalone compiler called HeliOS_cmp, and we will below enter into a detailed discussion of the use of this compiler and its associated "executive module" HeliOS_exe. ************************* HeliOS_cmp and HeliOS_exe ************************* The full HeliOS system consists of the integrated interpreter/compiler program called "HeliOS_int" and two smaller programs which act as a stand-alone compiler (called "HeliOS_cmp") and an executive (called "HeliOS_exe"). * WARNING! The "HeliOS_exe" file is an ordinary AmigaDOS executable file which is provided on your HeliOS master disks in uncompressed form. If you wish, you may use a packer such as PowerPacker to compress this executable into a file somewhat less than half the size of the original, thus enabling you to save space on any of your HeliOS program disks which run HeliOS overlay files using HeliOS_exe. Please note however that the copy of "HeliOS_exe" which resides in your master "HeliOS:" directory MUST NOT BE PACKED. This is because this file is used in its UNPACKED form by the main HeliOS Interpreter program when it is creating standalone executables. If you pack the "HeliOS_exe" file which is in the HeliOS: directory you will find that all standalone HeliOS programs created from the Interpreter will not work at all. *************************** Simple useage of HeliOS_cmp *************************** You can compile any HeliOS source code using the stand-alone compiler, HeliOS_cmp, using an AmigaDOS command line such as: HeliOS_cmp HeliOS:MyPrograms/MySourceCode ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Single command line parameter = name of the HeliOS source code The use of HeliOS_cmp will create two new files which will be stored in the same path as the original source code file, and are based on the original source code filename with additional suffixes: 1. The first file will be called "MySourceCode.cmp", and is a compiled HeliOS program module. This file always has the suffix ".cmp". 2. The second file will be called "MySourceCode.cmpV", and is a compiled HeliOS vocabulary module This file always has the suffix ".cmpV". *************************** Simple useage of HeliOS_exe *************************** The compiled program module (the file with the ".cmp" suffix) generated using HeliOS_cmp as described above can be executed by using the stand- alone HeliOS executive program, HeliOS_exe. The HeliOS_exe program is used from an AmigaDOS command line with a single parameter, like this: HeliOS_exe HeliOS:MyPrograms/MySourceCode.cmp ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Single command line parameter = name of the HeliOS compiled code module Although the HeliOS_cmp program generates by default a program module with a ".cmp" suffix to its filename, this name can be changed before using the file with HeliOS_exe. In other words, HeliOS_exe does NOT require any special filename format for its program module filename parameter. N.B. The use of HeliOS_exe does not require the vocabulary module, which is only needed when you are using the full HeliOS interpreter. The compiled vocabulary module is used automatically by HeliOS when PRELOADING the compiled program into the main HeliOS interpreter. **************************** Special useage of HeliOS_cmp **************************** As stated above, the normal simple useage of HeliOS_cmp is: HeliOS_cmp SourceFile Also as stated above, this simple useage takes as a single parameter the filename of the source code file which you wish to compile, and creates a compiled code module and a vocabulary module. These "module" files have the same name as the original file but with ".cmp" and ".cmpV" as filename suffixes. For more flexible use of HeliOS_cmp you can specify various different actions by using extra command line parameters: 1. You can specify your own specific output filename and path. To do this you must specify the target output filename (with path) as a second command line parameter placed after the source file name, like this: HeliOS_cmp SourceFile TargetFile ^^^^^^^^^^ 2nd parameter = Target output filename and path If you do not specify a full path, HeliOS will save the output file to the current directory. In this case HeliOS_cmp will open a 4-colour screen. In this case a final end-of-compilation message and a free bytes statement will apppear. 2. You can specify that no vocabulary module file is created. To do this you must specify the command line switch "-v" after the other command line parameters: HeliOS_cmp SourceFile -v ^^ Specifies no vocabulary module file HeliOS_cmp SourceFile TargetFile -v ^^ Specifies no vocabulary module file In this case HeliOS_cmp will open a 4-colour screen. In this case a final end-of-compilation message and a free bytes statement will apppear. 3. You can specify that no output files at all are created. To do this you must specify the command line parameter "NULL" as the second parameter: HeliOS_cmp SourceFile NULL ^^^ Specifies no output module files at all or HeliOS_cmp SourceFile null ^^^ Specifies no output module files at all Note that the "NULL" parameter may be specified in upper or lower case. In this case HeliOS_cmp will open an 8-colour screen and set its colours to your default HeliOS colour settings. In this case the final end-of-compilation message and the free bytes statement will not apppear. This mode of operation allows you to use the HeliOS_cmp program to execute source code "cleanly", with no output files created, for the purpose of running code outside the main interprter. In effect this can be used as a method of "executing" HeliOS source code, since the compiler can be caused by the source code itself to evoke the final run time program. **************************************** Editing and compiling HeliOS source code **************************************** Normally it is convenient to develop your code using the interactive HeliOS system. Alternatively, if you prefer to do so, you can use a separate text editor to produce your source code and then compile and run it using the HeliOS standalone compiler/executive. Whatever you do, you MUST use the stand-alone compiler if you intend to redistribute your programs. Failure to comply with this is an infringement of Helios copyright - you MUST NOT redistribute the full HeliOS interpreter/compiler. ******************************************************** A note on saving and loading HeliOS Interpreter programs ******************************************************** The HeliOS menu functions PRESAVE and PRELOAD are used to save and load the current state of the HeliOS system. When the PRELOAD function is used, the HeliOS system automatically runs the last word which was compiled in the dictionary before PRESAVEing. This gives you the option of "autorunning" programs, but if you do not want your program to do anything when it loads you can simply include a last word definition which does nothing. Like Forth, HeliOS programs consist of a code section and a section used to store the interpreter's vocabulary reference material, but HeliOS has a different method of organising its dictionary to standard Forth systems. HeliOS stores all textual "name" information outside the main dictionary in a separate module, and incidentally employs a hashing system with multi-path searching to achieve very fast compilation. When you save out a "precompiled" module from the main interpreter, two files are always generated, one of which is a vocabulary text module, and the other contains compiled HeliOS code. This is also the case when you use the HeliOS_cmp compiler program in its default mode of operation. The compiled code module will be given the name which you specify, and the vocabulary module will have the same name with a "V" suffix added. In order to reload a precompiled module ino the interpreter you must select and load the CODE file, and the "V" file will automatically be picked up and loaded by HeliOS. If the "V" file is not available the module will not load into the HeliOS interpreter, so remember to move both files if you are transferring your code from one disk to another. ********* IMPORTANT ********* Remember: when using the main interpreter, compiled modules employ TWO files, one of which is a vocabulary text module. The stand-alone executive HeliOS_exe does NOT require a vocabulary module. ********************************************** Saving and loading HeliOS Stand-Alone programs ********************************************** The stand-alone compiler operates differently from the Interpreter in that the vocabulary name information is discarded after compilation, leaving a single very compact code module. This single code module is then loaded by the HeliOS executive program and runs your code. So, when using the stand-alone compiler/executive, compiled modules employ only ONE file. Another important point to remember when designing stand-alone code is that the main HeliOS interpreter screen environment, file requester, and editor WILL NOT BE AVAILABLE! * In stand-alone code you MUST set up a screen display for your output, and you must not rely on the HeliOS file requester or editor being available. * Remember also that no vocabulary name information will be available, so do not use code which relies on this at run time: dictionary searches are not possible when the vocabulary name information has been removed! * It will also be necessary to explicitly load any include files needed by using a command within the program, since the HeliOS interpreter with its preloaded include files is not available. ************************************* Using the HeliOS stand-alone compiler ************************************* The stand-alone compiler is invoked from the CLI by typing its program name (ie. "HeliOS_cmp") followed by the name of your source code file and possibly other parameters as specified above. The compiler will present you with a full screen window and will proceed to compile your code. Any errors will be reported in the window, with the usual information on the type and position of the the error. Finally, you will be given a statement of how much dictionary space is still available, and then the compiler waits for you to click in the screen to indicate that you are ready to go on. Assuming the compilation is successful the compiler will generate a file with the same name and in the same path as your original source file but with a ".cmp" suffix (as default action, but see above for special use). ************************************** Using the HeliOS stand-alone executive ************************************** To run your compiled code you must type at the CLI the name of the HeliOS executive program (ie. "HeliOS_exe") followed by the name of the compiled code file. Remember that you do not have to retain the ".cmp" suffix on the compiled file, which was merely added for identification purposes by the compiler. ************************************ Start up procedure for compiled code ************************************ When precompiled code is run by HeliOS, the last (topmost) word in the dictionary is automatically executed. This gives you the opportunity to automatically start your program, and is necessary when using standalone modules. See above for a discussion of this feature when applied to PRESAVEing and PRELOADing code in the Interpreter environment. ******* Summary ******* The main interpreter/compiler saves and loads twin-file modules The standalone compiler/executive saves and loads single file modules but can also generate vocabulary modules if required Modules generated from the interpreter and the stand-alone compiler are NOT necessarily interchangeable The standalone compiler/executive code cannot use the standard HeliOS Interpreter screen/window output, the HeliOS FileIO requester, the HeliOS editors, or any run time vocabulary access. The standalone compiler/executive code must specify and load any include files required in an explicit statement within the program. The main interpreter/compiler is called "HeliOS_int" The stand-alone compiler is called "HeliOS_cmp" The stand-alone executive is called "HeliOS_exe" "HeliOS_cmp" and "HeliOS_exe" may be invoked from the CLI followed by simple command line parameters as specified above. When running precompiled code HeliOS automatically executes the top word in the dictionary, giving you control over startup execution. You can use the above feature to customise your startup environment in the interpreter. In the main interpreter there is a menu allowing the compilation, saving, and loading of complete code modules: this process is referred to as PRESAVEing and PRELOADing. ************************************************************************ End ************************************************************************